Shareware Grab Bag/Shareware Grab Bag.iso/007/tsr25src.arc/TSR.DOC

Text File | 1987-06-02 | 22KB | 525 lines

****************************************************************
*                TSR Utilities Version 2.5                     *
*   The TSR Utilities include programs useful in managing      *
*   DOS memory, and in particular managing memory-resident     *
*  utilities. TSR stands for "Terminate and Stay Resident".    *
*                                                              *
****************************************************************

A. Introduction
================================================================

The TSR Utilities have grown to include 8 programs. Here's a
quick overview of each one:

  MARK - marks a position above which TSRs can be released.
  RELEASE - removes TSRs from memory.
  FMARK - performs the same function as MARK but uses less memory.
  MAPMEM - shows what memory resident programs are loaded.
  WATCH - a TSR itself, it keeps detailed records of other TSRs.
  DISABLE - disables or reactivates TSRs kept in memory.
  RAMFREE - shows how much RAM memory is available.
  EATMEM - uses up memory for controlled program testing.

The programs are described in more detail in the following
sections.


B. MARK, FMARK and RELEASE
================================================================

MARK.COM and RELEASE.COM are used to remove memory-resident
programs from memory, without requiring a system reboot, and
without the usual problems of creating holes or leaving
interrupts dangling. The two programs are used simply as follows:

1) Run the program MARK.COM before installing any memory-
   resident program that you may wish to deinstall later.
   This marks the current position in memory and stores the
   DOS interrupt vector table (all interrupts from 0 to FFH).

2) Install whatever TSRs that you want to use, in the normal
   way that you install them.

3) When you want to deinstall all TSRs above the last MARK,
   run the program RELEASE.COM. This will release all of the
   memory above (and including) the last MARK, and restore
   all interrupt vectors taken over by the memory resident
   programs.

MARK and RELEASE can be "stacked" as many times as desired.
RELEASE releases the memory above the last MARK call. MARK uses
about 1600 bytes of memory each time it is called. This 1600
byte region is also released when a RELEASE is done. MARK memory
usage is dominated by the copies of the DOS interrupt vector
table (interrupts 0..FFh) and the copy of the EMS page map
(blocks 0..31 only) which MARK keeps when it goes resident.

----------------------------------------------------------------

MARK and RELEASE can optionally be called with a single command
line parameter:

  MARK MarkName
  RELEASE MarkName

In this way a particular mark is given a name. Calling RELEASE
with the same name will release all memory above and including
the mark of that name, also releasing any intermediate marks in
the process. If no mark of the proper name is found, RELEASE
will halt with a warning. A RELEASE call with no MarkName
specified will release the last MARK, whether or not that MARK
was named.

The MarkName can be any text string up to 126 characters in
length. It may not contain embedded blanks or tabs. Case (upper
or lower) is not important when matching MarkNames.

MarkName supports an additional feature. If the MarkName begins
with ! (exclamation point), then the mark is called a "protected
mark". That mark can be released *only* by an exact match to its
name (including the exclamation point). A protected mark will
NOT be released with an "unnamed" RELEASE. Any named or unnamed
RELEASE will stop without releasing any memory if it encounters
a protected mark that it does not match exactly.

----------------------------------------------------------------

As of version 1.4, MARK and RELEASE also control Expanded memory
(Lotus/Intel/Microsoft EMS). They have been tested with READY!
and with the TurboPower Software expanded memory disk cache, as
well as with the device drivers used by the STB Expanded Memory
Card.

WARNING: if a resident application allocates expanded memory at
some time *after* going resident and after the last MARK made,
that expanded memory will be released by a call to RELEASE. The
current expanded memory manager (EMM) does not give us enough
information to avoid this possibility. Fortunately, there are no
known memory resident programs which perform this dynamic
allocation of expanded memory. We hope that the EMM will be
upgraded before such applications are designed.

----------------------------------------------------------------

As of version 1.6, RELEASE takes special precautions to allow it
to release extra invocations of the DOS command processor. In
the simplest form, an extra command processor is obtained by
typing COMMAND at the DOS level. Many multitasking or switching
utilities also utilize this feature of DOS, and these utilities
can now be managed via MARK and RELEASE.

----------------------------------------------------------------

Due to the way DOS handles batch files, there are certain
limitations on using RELEASE within batch. You *cannot* perform
the following sequence of events successfully:

First, from the DOS command line:

  MARK
  SK      {SideKick, or any other resident program or programs}

Then, within a batch file:

  RELEASE {get rid of SK and MARK}
  LOTUS   {run Lotus using the additional memory}
  MARK    {put SK back in place}
  SK

DOS allocates a small memory block prior to running any batch
file. It does not allow that block to be deallocated from within
the batch file without various errors occurring. As a result, in
this case the MARK and SK memory blocks are effectively trapped
until the batch file is completed, after which the memory will
be reusable. Indeed, if you run the batch file presented above,
you will get MARK and SK installed above a big hole in memory
left by the previous images of MARK and SK.

As of version 1.9, RELEASE guards against this possibility. If
it senses that you are attempting to release memory trapped by a
"batch control block", it writes a warning message to that
effect. It still releases the memory, but when it exits it
passes back a return code of 1 rather than the usual value of 0.

You *can* obtain the desired effect in at least two other ways.
First, you could make two batch files and call them one after the
other:

Batch file #1:
  RELEASE

Batch file #2:
  LOTUS
  MARK
  SK

In this case, running RELEASE in batch file #1 has the same
effect as running RELEASE from the DOS command line. However,
directly calling the second batch file from the first doesn't
always seem to work either. The only sure bet appears to be the
use of a keypoker like STACKEY, KEY-FAKE or PCED's KEYIN,
modifying Batch #1 as follows:

  RELEASE
  KEY-FAKE "batch2" 13

A better way to make these things happen is to use the public
domain program CED, or its commercial upgrade PCED. These
programs allow you to define "synonyms" for groups of commands.
The commands execute one after the other just like a batch file.
However, the synonyms do not create an extra batch control
memory block which causes the problems just described.

Thus you could make two CED synonyms as follows. (We assume that
the CED "chain character" is ^).

SYN LOADSK 'mark !sk^sk'
  {create a protected sidekick marker and load sidekick}

SYN RUNLOT 'release !sk^lotus^mark !sk^sk'
  {release sidekick if it's there, run lotus, then reload sidekick}

Note: you can obtain PCED by calling Cove Software at
301-992-9371.

----------------------------------------------------------------

Regarding PCED, please note the following: PCED supports
"user-installed commands" such as KEYIN, HS, RAW and others. MARK
and RELEASE are unable to release these user-installed commands
individually. That is, if your AUTOEXEC.BAT looked like the
following:

  CED
  MARK
  KEYINST

then typing RELEASE would sooner or later cause your system to
crash. RELEASE cannot inform PCED that its installed command is
gone, and PCED will continue to try to use code which is no
longer in memory.

PCED itself provides a "KILL" command which removes
specified user-installed programs from memory. Use the KILL
command if you want to remove PCED's user-installed commands from
memory.

MARK and RELEASE can safely be used with PCED's commands as long
as PCED itself is removed from memory when the commands are.

----------------------------------------------------------------

As of version 2.0, a new form of marking, called a "file
mark", is also supported. The new mark has the advantage that it
uses only about 150 bytes of memory rather than the 1600 of MARK.

The new mark is placed with the command

    FMARK [d:][directory]filename

The bulk of the vector table and EMS page map are stored in the
file which you specify on the command line rather than in
memory. Note that a command line parameter is *required* in this
case. Otherwise FMARK will halt with an error. The file created
by FMARK will be between 1000 and 2000 bytes in size, depending
on usage of expanded memory.

If you will switch drives or directories after using FMARK, you
should specify a complete pathname when FMARK is initially
called. To avoid confusion, you may want to keep the FMARK files
in the root directory, or in a separate directory defined just
for this purpose.

The RELEASE program can release either an in-memory mark (placed
by MARK.COM) or a file mark (placed by FMARK.COM). Use of RELEASE
with in-memory marks is described above. To use RELEASE with
file marks, call it with the name of the mark file on the command
line:

    RELEASE [d:][directory]filename

In this case the filename must be specified on the command line,
and only a file mark *exactly* matching the command line will be
released. If the specified mark file is not found, RELEASE will
halt with an error message. When the memory is released, the mark
file is also deleted from disk.

There is no direct equivalent of protected marks for FMARK. If
an unnamed RELEASE finds an in-memory mark below a file mark,
the file mark will be released in the process of the unnamed
release. In this case, the mark file will not be deleted from
disk.

----------------------------------------------------------------

Version 2.1 of RELEASE fixes a stupid bug in 2.0. This bug lead
to reports of RELEASE printing its status message on the
printer, and to some system crashes. The bug was caused by
writing over the first two bytes of the DOS file handle table at
offset 0018H in the PSP.

----------------------------------------------------------------

Version 2.2 of RELEASE adds a few new features. These features
are activated by command line switches. The valid switches are
as follows:

  /K    release memory above the specified MARK, but Keep the
        MARK itself in memory. This switch is useful if you plan
        to reinstall the released TSRs later.

  /R    Revector the 8259 interrupt controller(s) to powerup
        state. This option is useful for TSRs that patch in to
        the system at a very low level. Examples include network
        operating system shells, multitaskers, etc. Use this
        option with caution; that is, test it at a time when
        no useful work is loaded into memory.

  /?    Show a brief help screen and halt.

Any of these options are acceptable when preceded by a '-', for
example, -K instead of /K.

The /R option now allows the release of DesqView, Windows, and
TaskView from memory. We hope that it will allow the release of
network shells, but have not been able to test it. DoubleDOS
unfortunately cannot be released even with the /R option. (It
apparently patches DOS itself when it is installed.)

Version 2.2 of RELEASE also restores a few additional memory
locations from the MARK. It restores 8 bytes at 40:A8
(associated with the EGA) and 16 bytes at 40:F0 (the
interapplications communications area).

----------------------------------------------------------------

Version 2.3 of RELEASE adds support for the new WATCH feature of
the TSR Utilities. There will be no apparent difference in
RELEASE's behavior, but behind the scenes, it is updating the
WATCH data area whenever you release TSRs from memory.

----------------------------------------------------------------

Version 2.4 of RELEASE slightly changes the way that EMS expanded
memory is managed. We have had a number of reports of EMS clones
in which one of the EMS library functions that we use is not
correctly implemented. Since there is an alternate means of
getting the same information, and apparently the alternate means
is more reliably implemented, we have changed RELEASE (and
MAPMEM). See the source code if you care about the details.

We have also added a new RELEASE command line switch, /N, which
causes RELEASE to avoid touching EMS memory at all. Since so few
memory resident programs use expanded memory, this switch will
allow RELEASE to be used for the majority of programs even if a
conflict with the EMS driver occurs.


C. MAPMEM and WATCH
================================================================

MAPMEM.COM is used to display the current DOS memory map. It shows
the resident programs, how much memory they use, and what interrupt
vectors each currently controls. MAPMEM also shows information
about expanded memory when such a driver is installed. MAPMEM
writes to the standard output -- thus the output can be printed
or stored to a file by using DOS redirection.

MAPMEM shows MARKs and FMARKs so that you can examine them prior
to a RELEASE. A MARK will show the owner name "MARK", and the
mark name (if any) in the command line area. An FMARK will show
"N/A" in the owner column (due to the minimal memory kept by an
FMARK), and the name of the mark file in the command line area.

MAPMEM supports the following command line options:

     /V     Verbose report.
     /?     Write a brief help screen.

MAPMEM accepts either "/" or "-" to delimit the command line
options.

On the Verbose report, the "Files" column shows the number of
file handles that each resident block has kept open. Each block
of memory reported by DOS is listed individually in verbose
mode. This is useful in debugging problems, either with the TSR
Utilities themselves, or perhaps with the resident programs that
you are using.

By default, each "hooked vector" that MAPMEM reports shows only
the current owner of the vector. Any previous owners now chained
onto the list are not shown. Because of the technique used,
MAPMEM may report some bogus hooked vectors (generally high
numbered ones). If WATCH has been installed, however, MAPMEM
reads the WATCH information area in memory and shows the vectors
for which any TSR gains control. No bogus values should appear
in this case.

----------------------------------------------------------------

WATCH.COM is a resident program that keeps track of other memory
resident programs. As a TSR goes resident, WATCH updates a data
area in memory that contains information about what interrupt
vectors were taken over. This information can later be used by
MAPMEM and DISABLE to show more details about interrupts than
normally available.

Installation of WATCH.COM is optional. All of the TSR Utilities
except DISABLE can be used whether or not WATCH is installed.

If you want to use it, WATCH.COM should be installed as the
first TSR in your AUTOEXEC.BAT file. WATCH uses about 4000 bytes
of memory when it is installed. Most of this memory holds various
information about the TSRs installed in the system -- it includes
two copies of the interrupt vector table, and one data area which
shows what interrupt vectors were taken over by each TSR. This
information is used by DISABLE to deactivate and reactivate TSRs
without removing them from memory.


D. DISABLE
================================================================

DISABLE is a program new to TSR Utilities version 2.3. With it,
you can disable and reenable specified memory resident programs
without removing them from memory. Its function is analogous to
that performed by REFEREE from Persoft, although DISABLE has
neither a fancy user interface nor an option to work from within
other programs. DISABLE can allow conflicting TSRs to coexist.

In order to use DISABLE, you must install WATCH.COM as the first
memory resident program in your system. WATCH keeps the detailed
information about each memory resident program that DISABLE uses
to later control them.

Like the other TSR Utilities, DISABLE is operated from the
command line. You specify a single TSR by its name (if you are
running DOS 3.x) or by its address as determined from a MAPMEM
report. If you specify an address, immediately precede the
address with a dollar sign "$" and specify the address in
hexadecimal.

The name specified for a TSR is the one reported by MAPMEM in the
"owner" column. If the owner column reports "N/A", then you must
instead specify the address from the "PSP" column.

DISABLE accepts the following command line syntax:

  DISABLE TSRname|$PSPaddress [Options]

Options may be preceded by either / or -. Valid options
are as follows:

     /A     reActivate the specified TSR.
     /?     Write a brief help screen.

If no option is specified, DISABLE will disable the named TSR.

Examples of usage:
  DISABLE SK        {disables SideKick}
  DISABLE SK /A     {reenables SideKick}
  DISABLE $2F2E     {disables the TSR at address 2F2E}

MAPMEM will indicate disabled TSRs by displaying the word
"disabled" in the interrupt vector column of the report.


E. RAMFREE and EATMEM
================================================================

RAMFREE.COM supplies a fast way to determine the amount of free
RAM without going through CHKDSK. Just type RAMFREE and it will
quickly report the free bytes of RAM.

EATMEM.COM is useful for program development. When you want to
test software in an environment with a desired amount of
available memory, EATMEM will install itself to use up any
desired amount. The memory used by EATMEM can be freed by using
MARK and RELEASE. Call EATMEM with a single command line
parameter, specifying the (decimal) number of KILOBYTES to eat
up:

  EATMEM KiloBytesToEat

EATMEM will happily allow you to eat up all available memory,
leading to a system crash when COMMAND.COM cannot be reloaded. Be
sure to calculate how much memory to use before calling EATMEM.


F. The Story Behind the TSR Utilities
================================================================

These programs should work on any system running PC-DOS or MS-DOS
2.0 or later. They were developed on a Compaq Deskpro 286 running
Compaq DOS 3.0 and have subsequently been tested on a number of
different systems.

Complete source code for the TSR Utilities is available in the
file TSRSRC.ARC. MARK, FMARK, WATCH, RAMFREE and EATMEM are
written in assembly language (MASM), while DISABLE, MAPMEM and
RELEASE are written in Turbo Pascal. TSRSRC requires that you
have Turbo Pascal version 3. On CompuServe, TSRSRC is found in
the Borland SIG (Go BOR-100) in data library 3 (DL3).

These programs are copyrighted, but may be freely distributed for
personal, non-commercial use. You may use them yourself, give
them to your friends or co-workers, or distribute them for a
cost-based fee as part of a user's group or bulletin board
service. If you wish to distribute these programs as part of a
commercial package, please contact us for a license agreement.

These programs were originally developed as an exercise in
understanding DOS memory management. We request no donation.
However, we will request $10 to cover our cost and time if you
ask us to ship a disk to you.

TurboPower Software is in the business of Turbo Pascal
programming tools for serious developers. Our first product, the
TurboPower Utilities, contains 9 programs including an
intelligent cross-referencer, a pretty printer, an execution
profiler and several DOS file and text management tools.

Our second product, Turbo EXTENDER, lets Turbo Pascal programs
grow beyond 64K bytes in size via modular compilation and
linking. It also provides a toolbox of routines for virtual array
management, as well as analytical tools for overlayed programs.

Our third product, T-DebugPLUS, is an expanded and fully
supported version of the popular public domain program TDEBUG. It
includes both a fully symbolic debugger integrated with the Turbo
Pascal development environment, and also the ability to generate
DOS standard MAP files for use with other external symbolic
debuggers such as Periscope, Symdeb, and Atron.

If you have seen prior versions of the TSR Utilities, you may
note that the COM files in version 2.5 are significantly smaller
than before. The assembler programs are smaller due to a
conversion to the MicroSoft assembler, which allowed us to keep
static data structures out of the COM files. The Pascal programs
are smaller due to the application of TurboPower Software's new
product, Turbo Optimizer. Optimizer automatically removes the
unused portions of Turbo Pascal's runtime library, and also
optimizes the compiler generated code, making it smaller and
faster.

The TSR Utilities were written by Kim Kokkonen, with thanks to
Neil Rubenking for the original idea behind MARK and RELEASE.
Also my thanks to Richard Wilson and Barry Simon at CalTech for
the idea that lead to FMARK, and for much useful correspondence
about the TSR Utilities.

We can be reached at:

     TurboPower Software
     3109 Scotts Valley Drive #122
     Scotts Valley, CA 95066
     408-438-8608 (voice only, Monday-Friday 9AM-5PM)
     Compuserve: 72457,2131

Version 2.5 - 6/2/87 - fixes some minor bugs, and adds
  version checking between MARK and RELEASE.

The TSR Utilities are Copyright (c) 1986,1987 by Kim Kokkonen.
All Rights Reserved.